home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1998 October / Macworld (1998-10).dmg / Shareware World / Info / For Developers / MacZoop 1.8.4 / More Classes / Streaming Classes / ZStream.h < prev   
Encoding:
C/C++ Source or Header  |  1998-05-10  |  4.9 KB  |  148 lines  |  [TEXT/CWIE]
  1. /*************************************************************************************************
  2. *
  3. *
  4. *            MacZoop - "the framework for the rest of us"         
  5. *
  6. *
  7. *
  8. *            ZStream.h            -- a generic stream (abstract class- use ZHandleStream or
  9. *                                                                        ZFileStream ).
  10. *
  11. *
  12. *
  13. *
  14. *
  15. *            © 1998, Graham Cox
  16. *
  17. *
  18. *
  19. *
  20. *************************************************************************************************/
  21.  
  22.  
  23. #pragma once
  24.  
  25. #ifndef __ZSTREAM__
  26. #define    __ZSTREAM__
  27.  
  28. class    ZObject;
  29. class    ZArray;
  30.  
  31. typedef struct
  32. {
  33.     ZObject*    theObject;
  34.     long        instanceID;
  35.     long        classID;
  36. }
  37. ObjRef_T_Entry;
  38.  
  39. // class definition:
  40.  
  41. class    ZStream
  42. {
  43. protected:
  44.     unsigned long    idSeed;
  45.     unsigned long    mark;
  46.     ZArray*            refTable;
  47.  
  48. public:
  49.  
  50.     ZStream();
  51.     virtual ~ZStream();
  52.     
  53.     virtual void        Reset() { mark = 0; };
  54.  
  55. // reading data from stream    
  56.  
  57.     virtual void        ReadChar( char* aChar );
  58.     virtual void        ReadShort( short* aShort );
  59.     virtual void        ReadLong( long* aLong );
  60.     virtual void        ReadFloat( float* aFloat );
  61.     virtual void        ReadString( Str255 aString );
  62.     virtual void        ReadData( Ptr aBuf, long* dataLen );
  63.     virtual void        ReadHandle( Handle* aHand );
  64.     virtual ZObject*    ReadObject();
  65.     virtual void        ReadRect( Rect* aRect );
  66.     virtual void        ReadPoint( Point* aPoint );
  67.     virtual void        ReadGrafPort( GrafPtr aPort );
  68.     virtual void        ReadColour( RGBColor* rgb );
  69.     
  70. // writing data to the stream
  71.  
  72.     virtual void        WriteChar( char aChar );
  73.     virtual void        WriteShort( short aShort );
  74.     virtual void        WriteLong( long aLong );
  75.     virtual void        WriteFloat( float aFloat );
  76.     virtual void        WriteString( Str255 aString );
  77.     virtual void        WriteData( Ptr aBuf, long dataLen );
  78.     virtual void        WriteHandle( Handle aHand );
  79.     virtual void        WriteObject( ZObject* anObject );
  80.     virtual void        WriteRect( Rect* aRect );
  81.     virtual void        WritePoint( Point aPoint );
  82.     virtual void        WriteGrafPort( GrafPtr aPort );
  83.     virtual void        WriteColour( RGBColor* rgb );
  84.     
  85.     virtual void        Skip( long skipBytes ) { mark += skipBytes; };
  86.     
  87. protected:
  88.  
  89. // low level stuff
  90.  
  91.     virtual void        PutTo( void* data, long size ) = 0;
  92.     virtual void        GetFrom( void* data, long* size ) = 0;
  93.     virtual long        FindObjectReference( ZObject* anObject );
  94.     virtual long        FindObjectReference( long classID, long instanceID );
  95. };
  96.  
  97.  
  98. enum
  99. {
  100.     kNoMoreDataInStreamErr    = 611,        // tried to read beyond the end-of-stream (eos)
  101.     kStreamsNotPresentErr
  102. };
  103.  
  104.  
  105. /*
  106.  
  107. Use STREAMS to save and restore any data. ZStream is an abstract class and as such does nothing,
  108. but implements the basic behaviour used by ZHandleStream and ZFileStream. Since both have the
  109. same API, saving data in memory or on disk follows exactly the same protocol. You can write
  110. whole objects to a stream as long as they are derived from ZObject- just call the object's
  111. WriteToStream method, passing the stream object. To read an object from a stream, you need to
  112. make the object using the default constructor, then call its ReadFromStream method, passing
  113. the stream, which will set up the object from the stream. Internally, the objects make calls
  114. to the stream's methods here to write data members, etc to the stream. They can also cause
  115. other objects to be written there by calling their WriteToStream, etc. This is the basis of
  116. persistent objects.
  117.  
  118. In order to resolve object references when more than one object may wish to write it to a
  119. stream, you must call WriteObjectReference for every object that you are going to try to
  120. put in the stream- this is done by the default WriteToStream() method in ZObject (objects
  121. MUST be saved to the stream in class hierarchy order, with the root class first, etc. ZStream
  122. keeps track of objects it has already written out and instead of doing it again will store a
  123. special code in the stream to indicate a shared object. If WriteObjectReference() returns TRUE,
  124. the object has not been seen and you should go ahead and save the object's data. If FALSE,
  125. the stream already has the object so you can skip the data save.
  126.  
  127. When reading in an object, the ReadFromStream() method should initialise itself from the
  128. root class upwards. If it needs to pull in another object, it must call the ReadObjectReference
  129. method here, which will return the object- either a new one built from the stream, or a
  130. pointer to an existing one if it was created already- in fact you do not need to care which it
  131. is, since the thing is fully initialised. Unlike the write to stream case, you should not
  132. explicitly call the object's ReadFromStream method.
  133.  
  134. Data is saved in the stream in the order it's appended, so it should clearly be read back in
  135. in the same order. Ensuring this is up to your code- basically, the read and write methods of
  136. an object should have identical structures, or use Skip() to ignore data on the stream.
  137.  
  138. Streams are extremely powerful for implementing files, drag/drop, cut/paste, undo and a whole
  139. host of other useful behaviours. Using persistent objects allows you to save and restore an
  140. entire hierarchy of objects, and also opens the door to building applications visually in the
  141. manner of visual C++, etc. 
  142.  
  143. */
  144.  
  145.  
  146.  
  147.  
  148. #endif